package com.gitee.wsl.collections.map.api

import com.gitee.wsl.collections.iterator.api.OrderedMapIterator

/**
 * Defines a map that maintains order and allows both forward and backward
 * iteration through that order.
 *
 * @param <K> the type of the keys in the map
 * @param <V> the type of the values in the map
 * @since 3.0
</V></K> */
interface OrderedMap<K, V> : Map<K, V> {
    /**
     * Gets the first key currently in this map.
     *
     * @return the first key currently in this map
     * @throws NoSuchElementException if this map is empty
     */
    fun firstKey(): K

    /**
     * Gets the last key currently in this map.
     *
     * @return the last key currently in this map
     * @throws NoSuchElementException if this map is empty
     */
    fun lastKey(): K

    /**
     * Obtains an `OrderedMapIterator` over the map.
     *
     *
     * An ordered map iterator is an efficient way of iterating over maps
     * in both directions.
     *
     *
     * @return a map iterator
     */
    fun mapIterator(): OrderedMapIterator<K, V>

    /**
     * Gets the next key after the one specified.
     *
     * @param key  the key to search for next from
     * @return the next key, null if no match or at end
     */
    fun nextKey(key: K): K?

    /**
     * Gets the previous key before the one specified.
     *
     * @param key  the key to search for previous from
     * @return the previous key, null if no match or at start
     */
    fun previousKey(key: K): K?
}